home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / usb.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  63.8 KB  |  1,733 lines
  1. #ifndef __LINUX_USB_H
  2. #define __LINUX_USB_H
  3.  
  4. #include <linux/mod_devicetable.h>
  5. #include <linux/usb/ch9.h>
  6.  
  7. #define USB_MAJOR            180
  8. #define USB_DEVICE_MAJOR        189
  9.  
  10.  
  11. #ifdef __KERNEL__
  12.  
  13. #include <linux/errno.h>        /* for -ENODEV */
  14. #include <linux/delay.h>    /* for mdelay() */
  15. #include <linux/interrupt.h>    /* for in_interrupt() */
  16. #include <linux/list.h>        /* for struct list_head */
  17. #include <linux/kref.h>        /* for struct kref */
  18. #include <linux/device.h>    /* for struct device */
  19. #include <linux/fs.h>        /* for struct file_operations */
  20. #include <linux/completion.h>    /* for struct completion */
  21. #include <linux/sched.h>    /* for current && schedule_timeout */
  22. #include <linux/mutex.h>    /* for struct mutex */
  23.  
  24. struct usb_device;
  25. struct usb_driver;
  26. struct wusb_dev;
  27.  
  28. /*-------------------------------------------------------------------------*/
  29.  
  30. /*
  31.  * Host-side wrappers for standard USB descriptors ... these are parsed
  32.  * from the data provided by devices.  Parsing turns them from a flat
  33.  * sequence of descriptors into a hierarchy:
  34.  *
  35.  *  - devices have one (usually) or more configs;
  36.  *  - configs have one (often) or more interfaces;
  37.  *  - interfaces have one (usually) or more settings;
  38.  *  - each interface setting has zero or (usually) more endpoints.
  39.  *
  40.  * And there might be other descriptors mixed in with those.
  41.  *
  42.  * Devices may also have class-specific or vendor-specific descriptors.
  43.  */
  44.  
  45. struct ep_device;
  46.  
  47. /**
  48.  * struct usb_host_endpoint - host-side endpoint descriptor and queue
  49.  * @desc: descriptor for this endpoint, wMaxPacketSize in native byteorder
  50.  * @urb_list: urbs queued to this endpoint; maintained by usbcore
  51.  * @hcpriv: for use by HCD; typically holds hardware dma queue head (QH)
  52.  *    with one or more transfer descriptors (TDs) per urb
  53.  * @ep_dev: ep_device for sysfs info
  54.  * @extra: descriptors following this endpoint in the configuration
  55.  * @extralen: how many bytes of "extra" are valid
  56.  * @enabled: URBs may be submitted to this endpoint
  57.  *
  58.  * USB requests are always queued to a given endpoint, identified by a
  59.  * descriptor within an active interface in a given USB configuration.
  60.  */
  61. struct usb_host_endpoint {
  62.     struct usb_endpoint_descriptor    desc;
  63.     struct list_head        urb_list;
  64.     void                *hcpriv;
  65.     struct ep_device         *ep_dev;    /* For sysfs info */
  66.  
  67.     unsigned char *extra;   /* Extra descriptors */
  68.     int extralen;
  69.     int enabled;
  70. };
  71.  
  72. /* host-side wrapper for one interface setting's parsed descriptors */
  73. struct usb_host_interface {
  74.     struct usb_interface_descriptor    desc;
  75.  
  76.     /* array of desc.bNumEndpoint endpoints associated with this
  77.      * interface setting.  these will be in no particular order.
  78.      */
  79.     struct usb_host_endpoint *endpoint;
  80.  
  81.     char *string;        /* iInterface string, if present */
  82.     unsigned char *extra;   /* Extra descriptors */
  83.     int extralen;
  84. };
  85.  
  86. enum usb_interface_condition {
  87.     USB_INTERFACE_UNBOUND = 0,
  88.     USB_INTERFACE_BINDING,
  89.     USB_INTERFACE_BOUND,
  90.     USB_INTERFACE_UNBINDING,
  91. };
  92.  
  93. /**
  94.  * struct usb_interface - what usb device drivers talk to
  95.  * @altsetting: array of interface structures, one for each alternate
  96.  *     setting that may be selected.  Each one includes a set of
  97.  *     endpoint configurations.  They will be in no particular order.
  98.  * @cur_altsetting: the current altsetting.
  99.  * @num_altsetting: number of altsettings defined.
  100.  * @intf_assoc: interface association descriptor
  101.  * @minor: the minor number assigned to this interface, if this
  102.  *    interface is bound to a driver that uses the USB major number.
  103.  *    If this interface does not use the USB major, this field should
  104.  *    be unused.  The driver should set this value in the probe()
  105.  *    function of the driver, after it has been assigned a minor
  106.  *    number from the USB core by calling usb_register_dev().
  107.  * @condition: binding state of the interface: not bound, binding
  108.  *    (in probe()), bound to a driver, or unbinding (in disconnect())
  109.  * @is_active: flag set when the interface is bound and not suspended.
  110.  * @sysfs_files_created: sysfs attributes exist
  111.  * @unregistering: flag set when the interface is being unregistered
  112.  * @needs_remote_wakeup: flag set when the driver requires remote-wakeup
  113.  *    capability during autosuspend.
  114.  * @needs_altsetting0: flag set when a set-interface request for altsetting 0
  115.  *    has been deferred.
  116.  * @needs_binding: flag set when the driver should be re-probed or unbound
  117.  *    following a reset or suspend operation it doesn't support.
  118.  * @dev: driver model's view of this device
  119.  * @usb_dev: if an interface is bound to the USB major, this will point
  120.  *    to the sysfs representation for that device.
  121.  * @pm_usage_cnt: PM usage counter for this interface; autosuspend is not
  122.  *    allowed unless the counter is 0.
  123.  *
  124.  * USB device drivers attach to interfaces on a physical device.  Each
  125.  * interface encapsulates a single high level function, such as feeding
  126.  * an audio stream to a speaker or reporting a change in a volume control.
  127.  * Many USB devices only have one interface.  The protocol used to talk to
  128.  * an interface's endpoints can be defined in a usb "class" specification,
  129.  * or by a product's vendor.  The (default) control endpoint is part of
  130.  * every interface, but is never listed among the interface's descriptors.
  131.  *
  132.  * The driver that is bound to the interface can use standard driver model
  133.  * calls such as dev_get_drvdata() on the dev member of this structure.
  134.  *
  135.  * Each interface may have alternate settings.  The initial configuration
  136.  * of a device sets altsetting 0, but the device driver can change
  137.  * that setting using usb_set_interface().  Alternate settings are often
  138.  * used to control the use of periodic endpoints, such as by having
  139.  * different endpoints use different amounts of reserved USB bandwidth.
  140.  * All standards-conformant USB devices that use isochronous endpoints
  141.  * will use them in non-default settings.
  142.  *
  143.  * The USB specification says that alternate setting numbers must run from
  144.  * 0 to one less than the total number of alternate settings.  But some
  145.  * devices manage to mess this up, and the structures aren't necessarily
  146.  * stored in numerical order anyhow.  Use usb_altnum_to_altsetting() to
  147.  * look up an alternate setting in the altsetting array based on its number.
  148.  */
  149. struct usb_interface {
  150.     /* array of alternate settings for this interface,
  151.      * stored in no particular order */
  152.     struct usb_host_interface *altsetting;
  153.  
  154.     struct usb_host_interface *cur_altsetting;    /* the currently
  155.                      * active alternate setting */
  156.     unsigned num_altsetting;    /* number of alternate settings */
  157.  
  158.     /* If there is an interface association descriptor then it will list
  159.      * the associated interfaces */
  160.     struct usb_interface_assoc_descriptor *intf_assoc;
  161.  
  162.     int minor;            /* minor number this interface is
  163.                      * bound to */
  164.     enum usb_interface_condition condition;        /* state of binding */
  165.     unsigned is_active:1;        /* the interface is not suspended */
  166.     unsigned sysfs_files_created:1;    /* the sysfs attributes exist */
  167.     unsigned unregistering:1;    /* unregistration is in progress */
  168.     unsigned needs_remote_wakeup:1;    /* driver requires remote wakeup */
  169.     unsigned needs_altsetting0:1;    /* switch to altsetting 0 is pending */
  170.     unsigned needs_binding:1;    /* needs delayed unbind/rebind */
  171.  
  172.     struct device dev;        /* interface specific device info */
  173.     struct device *usb_dev;
  174.     int pm_usage_cnt;        /* usage counter for autosuspend */
  175. };
  176. #define    to_usb_interface(d) container_of(d, struct usb_interface, dev)
  177. #define    interface_to_usbdev(intf) \
  178.     container_of(intf->dev.parent, struct usb_device, dev)
  179.  
  180. static inline void *usb_get_intfdata(struct usb_interface *intf)
  181. {
  182.     return dev_get_drvdata(&intf->dev);
  183. }
  184.  
  185. static inline void usb_set_intfdata(struct usb_interface *intf, void *data)
  186. {
  187.     dev_set_drvdata(&intf->dev, data);
  188. }
  189.  
  190. struct usb_interface *usb_get_intf(struct usb_interface *intf);
  191. void usb_put_intf(struct usb_interface *intf);
  192.  
  193. /* this maximum is arbitrary */
  194. #define USB_MAXINTERFACES    32
  195. #define USB_MAXIADS        USB_MAXINTERFACES/2
  196.  
  197. /**
  198.  * struct usb_interface_cache - long-term representation of a device interface
  199.  * @num_altsetting: number of altsettings defined.
  200.  * @ref: reference counter.
  201.  * @altsetting: variable-length array of interface structures, one for
  202.  *    each alternate setting that may be selected.  Each one includes a
  203.  *    set of endpoint configurations.  They will be in no particular order.
  204.  *
  205.  * These structures persist for the lifetime of a usb_device, unlike
  206.  * struct usb_interface (which persists only as long as its configuration
  207.  * is installed).  The altsetting arrays can be accessed through these
  208.  * structures at any time, permitting comparison of configurations and
  209.  * providing support for the /proc/bus/usb/devices pseudo-file.
  210.  */
  211. struct usb_interface_cache {
  212.     unsigned num_altsetting;    /* number of alternate settings */
  213.     struct kref ref;        /* reference counter */
  214.  
  215.     /* variable-length array of alternate settings for this interface,
  216.      * stored in no particular order */
  217.     struct usb_host_interface altsetting[0];
  218. };
  219. #define    ref_to_usb_interface_cache(r) \
  220.         container_of(r, struct usb_interface_cache, ref)
  221. #define    altsetting_to_usb_interface_cache(a) \
  222.         container_of(a, struct usb_interface_cache, altsetting[0])
  223.  
  224. /**
  225.  * struct usb_host_config - representation of a device's configuration
  226.  * @desc: the device's configuration descriptor.
  227.  * @string: pointer to the cached version of the iConfiguration string, if
  228.  *    present for this configuration.
  229.  * @intf_assoc: list of any interface association descriptors in this config
  230.  * @interface: array of pointers to usb_interface structures, one for each
  231.  *    interface in the configuration.  The number of interfaces is stored
  232.  *    in desc.bNumInterfaces.  These pointers are valid only while the
  233.  *    the configuration is active.
  234.  * @intf_cache: array of pointers to usb_interface_cache structures, one
  235.  *    for each interface in the configuration.  These structures exist
  236.  *    for the entire life of the device.
  237.  * @extra: pointer to buffer containing all extra descriptors associated
  238.  *    with this configuration (those preceding the first interface
  239.  *    descriptor).
  240.  * @extralen: length of the extra descriptors buffer.
  241.  *
  242.  * USB devices may have multiple configurations, but only one can be active
  243.  * at any time.  Each encapsulates a different operational environment;
  244.  * for example, a dual-speed device would have separate configurations for
  245.  * full-speed and high-speed operation.  The number of configurations
  246.  * available is stored in the device descriptor as bNumConfigurations.
  247.  *
  248.  * A configuration can contain multiple interfaces.  Each corresponds to
  249.  * a different function of the USB device, and all are available whenever
  250.  * the configuration is active.  The USB standard says that interfaces
  251.  * are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot
  252.  * of devices get this wrong.  In addition, the interface array is not
  253.  * guaranteed to be sorted in numerical order.  Use usb_ifnum_to_if() to
  254.  * look up an interface entry based on its number.
  255.  *
  256.  * Device drivers should not attempt to activate configurations.  The choice
  257.  * of which configuration to install is a policy decision based on such
  258.  * considerations as available power, functionality provided, and the user's
  259.  * desires (expressed through userspace tools).  However, drivers can call
  260.  * usb_reset_configuration() to reinitialize the current configuration and
  261.  * all its interfaces.
  262.  */
  263. struct usb_host_config {
  264.     struct usb_config_descriptor    desc;
  265.  
  266.     char *string;        /* iConfiguration string, if present */
  267.  
  268.     /* List of any Interface Association Descriptors in this
  269.      * configuration. */
  270.     struct usb_interface_assoc_descriptor *intf_assoc[USB_MAXIADS];
  271.  
  272.     /* the interfaces associated with this configuration,
  273.      * stored in no particular order */
  274.     struct usb_interface *interface[USB_MAXINTERFACES];
  275.  
  276.     /* Interface information available even when this is not the
  277.      * active configuration */
  278.     struct usb_interface_cache *intf_cache[USB_MAXINTERFACES];
  279.  
  280.     unsigned char *extra;   /* Extra descriptors */
  281.     int extralen;
  282. };
  283.  
  284. int __usb_get_extra_descriptor(char *buffer, unsigned size,
  285.     unsigned char type, void **ptr);
  286. #define usb_get_extra_descriptor(ifpoint, type, ptr) \
  287.                 __usb_get_extra_descriptor((ifpoint)->extra, \
  288.                 (ifpoint)->extralen, \
  289.                 type, (void **)ptr)
  290.  
  291. /* ----------------------------------------------------------------------- */
  292.  
  293. /* USB device number allocation bitmap */
  294. struct usb_devmap {
  295.     unsigned long devicemap[128 / (8*sizeof(unsigned long))];
  296. };
  297.  
  298. /*
  299.  * Allocated per bus (tree of devices) we have:
  300.  */
  301. struct usb_bus {
  302.     struct device *controller;    /* host/master side hardware */
  303.     int busnum;            /* Bus number (in order of reg) */
  304.     const char *bus_name;        /* stable id (PCI slot_name etc) */
  305.     u8 uses_dma;            /* Does the host controller use DMA? */
  306.     u8 otg_port;            /* 0, or number of OTG/HNP port */
  307.     unsigned is_b_host:1;        /* true during some HNP roleswitches */
  308.     unsigned b_hnp_enable:1;    /* OTG: did A-Host enable HNP? */
  309.  
  310.     int devnum_next;        /* Next open device number in
  311.                      * round-robin allocation */
  312.  
  313.     struct usb_devmap devmap;    /* device address allocation map */
  314.     struct usb_device *root_hub;    /* Root hub */
  315.     struct list_head bus_list;    /* list of busses */
  316.  
  317.     int bandwidth_allocated;    /* on this bus: how much of the time
  318.                      * reserved for periodic (intr/iso)
  319.                      * requests is used, on average?
  320.                      * Units: microseconds/frame.
  321.                      * Limits: Full/low speed reserve 90%,
  322.                      * while high speed reserves 80%.
  323.                      */
  324.     int bandwidth_int_reqs;        /* number of Interrupt requests */
  325.     int bandwidth_isoc_reqs;    /* number of Isoc. requests */
  326.  
  327. #ifdef CONFIG_USB_DEVICEFS
  328.     struct dentry *usbfs_dentry;    /* usbfs dentry entry for the bus */
  329. #endif
  330.     struct device *dev;        /* device for this bus */
  331.  
  332. #if defined(CONFIG_USB_MON)
  333.     struct mon_bus *mon_bus;    /* non-null when associated */
  334.     int monitored;            /* non-zero when monitored */
  335. #endif
  336. };
  337.  
  338. /* ----------------------------------------------------------------------- */
  339.  
  340. /* This is arbitrary.
  341.  * From USB 2.0 spec Table 11-13, offset 7, a hub can
  342.  * have up to 255 ports. The most yet reported is 10.
  343.  *
  344.  * Current Wireless USB host hardware (Intel i1480 for example) allows
  345.  * up to 22 devices to connect. Upcoming hardware might raise that
  346.  * limit. Because the arrays need to add a bit for hub status data, we
  347.  * do 31, so plus one evens out to four bytes.
  348.  */
  349. #define USB_MAXCHILDREN        (31)
  350.  
  351. struct usb_tt;
  352.  
  353. /**
  354.  * struct usb_device - kernel's representation of a USB device
  355.  * @devnum: device number; address on a USB bus
  356.  * @devpath: device ID string for use in messages (e.g., /port/...)
  357.  * @state: device state: configured, not attached, etc.
  358.  * @speed: device speed: high/full/low (or error)
  359.  * @tt: Transaction Translator info; used with low/full speed dev, highspeed hub
  360.  * @ttport: device port on that tt hub
  361.  * @toggle: one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
  362.  * @parent: our hub, unless we're the root
  363.  * @bus: bus we're part of
  364.  * @ep0: endpoint 0 data (default control pipe)
  365.  * @dev: generic device interface
  366.  * @descriptor: USB device descriptor
  367.  * @config: all of the device's configs
  368.  * @actconfig: the active configuration
  369.  * @ep_in: array of IN endpoints
  370.  * @ep_out: array of OUT endpoints
  371.  * @rawdescriptors: raw descriptors for each config
  372.  * @bus_mA: Current available from the bus
  373.  * @portnum: parent port number (origin 1)
  374.  * @level: number of USB hub ancestors
  375.  * @can_submit: URBs may be submitted
  376.  * @discon_suspended: disconnected while suspended
  377.  * @persist_enabled:  USB_PERSIST enabled for this device
  378.  * @have_langid: whether string_langid is valid
  379.  * @authorized: policy has said we can use it;
  380.  *    (user space) policy determines if we authorize this device to be
  381.  *    used or not. By default, wired USB devices are authorized.
  382.  *    WUSB devices are not, until we authorize them from user space.
  383.  *    FIXME -- complete doc
  384.  * @authenticated: Crypto authentication passed
  385.  * @wusb: device is Wireless USB
  386.  * @string_langid: language ID for strings
  387.  * @product: iProduct string, if present (static)
  388.  * @manufacturer: iManufacturer string, if present (static)
  389.  * @serial: iSerialNumber string, if present (static)
  390.  * @filelist: usbfs files that are open to this device
  391.  * @usb_classdev: USB class device that was created for usbfs device
  392.  *    access from userspace
  393.  * @usbfs_dentry: usbfs dentry entry for the device
  394.  * @maxchild: number of ports if hub
  395.  * @children: child devices - USB devices that are attached to this hub
  396.  * @pm_usage_cnt: usage counter for autosuspend
  397.  * @quirks: quirks of the whole device
  398.  * @urbnum: number of URBs submitted for the whole device
  399.  * @active_duration: total time device is not suspended
  400.  * @autosuspend: for delayed autosuspends
  401.  * @pm_mutex: protects PM operations
  402.  * @last_busy: time of last use
  403.  * @autosuspend_delay: in jiffies
  404.  * @connect_time: time device was first connected
  405.  * @auto_pm: autosuspend/resume in progress
  406.  * @do_remote_wakeup:  remote wakeup should be enabled
  407.  * @reset_resume: needs reset instead of resume
  408.  * @autosuspend_disabled: autosuspend disabled by the user
  409.  * @autoresume_disabled: autoresume disabled by the user
  410.  * @skip_sys_resume: skip the next system resume
  411.  *
  412.  * Notes:
  413.  * Usbcore drivers should not set usbdev->state directly.  Instead use
  414.  * usb_set_device_state().
  415.  */
  416. struct usb_device {
  417.     int        devnum;
  418.     char        devpath [16];
  419.     enum usb_device_state    state;
  420.     enum usb_device_speed    speed;
  421.  
  422.     struct usb_tt    *tt;
  423.     int        ttport;
  424.  
  425.     unsigned int toggle[2];
  426.  
  427.     struct usb_device *parent;
  428.     struct usb_bus *bus;
  429.     struct usb_host_endpoint ep0;
  430.  
  431.     struct device dev;
  432.  
  433.     struct usb_device_descriptor descriptor;
  434.     struct usb_host_config *config;
  435.  
  436.     struct usb_host_config *actconfig;
  437.     struct usb_host_endpoint *ep_in[16];
  438.     struct usb_host_endpoint *ep_out[16];
  439.  
  440.     char **rawdescriptors;
  441.  
  442.     unsigned short bus_mA;
  443.     u8 portnum;
  444.     u8 level;
  445.  
  446.     unsigned can_submit:1;
  447.     unsigned discon_suspended:1;
  448.     unsigned persist_enabled:1;
  449.     unsigned have_langid:1;
  450.     unsigned authorized:1;
  451.      unsigned authenticated:1;
  452.     unsigned wusb:1;
  453.     int string_langid;
  454.  
  455.     /* static strings from the device */
  456.     char *product;
  457.     char *manufacturer;
  458.     char *serial;
  459.  
  460.     struct list_head filelist;
  461. #ifdef CONFIG_USB_DEVICE_CLASS
  462.     struct device *usb_classdev;
  463. #endif
  464. #ifdef CONFIG_USB_DEVICEFS
  465.     struct dentry *usbfs_dentry;
  466. #endif
  467.  
  468.     int maxchild;
  469.     struct usb_device *children[USB_MAXCHILDREN];
  470.  
  471.     int pm_usage_cnt;
  472.     u32 quirks;
  473.     atomic_t urbnum;
  474.  
  475.     unsigned long active_duration;
  476.  
  477. #ifdef CONFIG_PM
  478.     struct delayed_work autosuspend;
  479.     struct mutex pm_mutex;
  480.  
  481.     unsigned long last_busy;
  482.     int autosuspend_delay;
  483.     unsigned long connect_time;
  484.  
  485.     unsigned auto_pm:1;
  486.     unsigned do_remote_wakeup:1;
  487.     unsigned reset_resume:1;
  488.     unsigned autosuspend_disabled:1;
  489.     unsigned autoresume_disabled:1;
  490.     unsigned skip_sys_resume:1;
  491. #endif
  492.     struct wusb_dev *wusb_dev;
  493. };
  494. #define    to_usb_device(d) container_of(d, struct usb_device, dev)
  495.  
  496. extern struct usb_device *usb_get_dev(struct usb_device *dev);
  497. extern void usb_put_dev(struct usb_device *dev);
  498.  
  499. /* USB device locking */
  500. #define usb_lock_device(udev)        down(&(udev)->dev.sem)
  501. #define usb_unlock_device(udev)        up(&(udev)->dev.sem)
  502. #define usb_trylock_device(udev)    down_trylock(&(udev)->dev.sem)
  503. extern int usb_lock_device_for_reset(struct usb_device *udev,
  504.                      const struct usb_interface *iface);
  505.  
  506. /* USB port reset for device reinitialization */
  507. extern int usb_reset_device(struct usb_device *dev);
  508.  
  509. extern struct usb_device *usb_find_device(u16 vendor_id, u16 product_id);
  510.  
  511. /* USB autosuspend and autoresume */
  512. #ifdef CONFIG_USB_SUSPEND
  513. extern int usb_autopm_set_interface(struct usb_interface *intf);
  514. extern int usb_autopm_get_interface(struct usb_interface *intf);
  515. extern void usb_autopm_put_interface(struct usb_interface *intf);
  516.  
  517. static inline void usb_autopm_enable(struct usb_interface *intf)
  518. {
  519.     intf->pm_usage_cnt = 0;
  520.     usb_autopm_set_interface(intf);
  521. }
  522.  
  523. static inline void usb_autopm_disable(struct usb_interface *intf)
  524. {
  525.     intf->pm_usage_cnt = 1;
  526.     usb_autopm_set_interface(intf);
  527. }
  528.  
  529. static inline void usb_mark_last_busy(struct usb_device *udev)
  530. {
  531.     udev->last_busy = jiffies;
  532. }
  533.  
  534. #else
  535.  
  536. static inline int usb_autopm_set_interface(struct usb_interface *intf)
  537. { return 0; }
  538.  
  539. static inline int usb_autopm_get_interface(struct usb_interface *intf)
  540. { return 0; }
  541.  
  542. static inline void usb_autopm_put_interface(struct usb_interface *intf)
  543. { }
  544. static inline void usb_autopm_enable(struct usb_interface *intf)
  545. { }
  546. static inline void usb_autopm_disable(struct usb_interface *intf)
  547. { }
  548. static inline void usb_mark_last_busy(struct usb_device *udev)
  549. { }
  550. #endif
  551.  
  552. /*-------------------------------------------------------------------------*/
  553.  
  554. /* for drivers using iso endpoints */
  555. extern int usb_get_current_frame_number(struct usb_device *usb_dev);
  556.  
  557. /* used these for multi-interface device registration */
  558. extern int usb_driver_claim_interface(struct usb_driver *driver,
  559.             struct usb_interface *iface, void *priv);
  560.  
  561. /**
  562.  * usb_interface_claimed - returns true iff an interface is claimed
  563.  * @iface: the interface being checked
  564.  *
  565.  * Returns true (nonzero) iff the interface is claimed, else false (zero).
  566.  * Callers must own the driver model's usb bus readlock.  So driver
  567.  * probe() entries don't need extra locking, but other call contexts
  568.  * may need to explicitly claim that lock.
  569.  *
  570.  */
  571. static inline int usb_interface_claimed(struct usb_interface *iface)
  572. {
  573.     return (iface->dev.driver != NULL);
  574. }
  575.  
  576. extern void usb_driver_release_interface(struct usb_driver *driver,
  577.             struct usb_interface *iface);
  578. const struct usb_device_id *usb_match_id(struct usb_interface *interface,
  579.                      const struct usb_device_id *id);
  580. extern int usb_match_one_id(struct usb_interface *interface,
  581.                 const struct usb_device_id *id);
  582.  
  583. extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
  584.         int minor);
  585. extern struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
  586.         unsigned ifnum);
  587. extern struct usb_host_interface *usb_altnum_to_altsetting(
  588.         const struct usb_interface *intf, unsigned int altnum);
  589.  
  590.  
  591. /**
  592.  * usb_make_path - returns stable device path in the usb tree
  593.  * @dev: the device whose path is being constructed
  594.  * @buf: where to put the string
  595.  * @size: how big is "buf"?
  596.  *
  597.  * Returns length of the string (> 0) or negative if size was too small.
  598.  *
  599.  * This identifier is intended to be "stable", reflecting physical paths in
  600.  * hardware such as physical bus addresses for host controllers or ports on
  601.  * USB hubs.  That makes it stay the same until systems are physically
  602.  * reconfigured, by re-cabling a tree of USB devices or by moving USB host
  603.  * controllers.  Adding and removing devices, including virtual root hubs
  604.  * in host controller driver modules, does not change these path identifers;
  605.  * neither does rebooting or re-enumerating.  These are more useful identifiers
  606.  * than changeable ("unstable") ones like bus numbers or device addresses.
  607.  *
  608.  * With a partial exception for devices connected to USB 2.0 root hubs, these
  609.  * identifiers are also predictable.  So long as the device tree isn't changed,
  610.  * plugging any USB device into a given hub port always gives it the same path.
  611.  * Because of the use of "companion" controllers, devices connected to ports on
  612.  * USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
  613.  * high speed, and a different one if they are full or low speed.
  614.  */
  615. static inline int usb_make_path(struct usb_device *dev, char *buf, size_t size)
  616. {
  617.     int actual;
  618.     actual = snprintf(buf, size, "usb-%s-%s", dev->bus->bus_name,
  619.               dev->devpath);
  620.     return (actual >= (int)size) ? -1 : actual;
  621. }
  622.  
  623. /*-------------------------------------------------------------------------*/
  624.  
  625. /**
  626.  * usb_endpoint_num - get the endpoint's number
  627.  * @epd: endpoint to be checked
  628.  *
  629.  * Returns @epd's number: 0 to 15.
  630.  */
  631. static inline int usb_endpoint_num(const struct usb_endpoint_descriptor *epd)
  632. {
  633.     return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
  634. }
  635.  
  636. /**
  637.  * usb_endpoint_type - get the endpoint's transfer type
  638.  * @epd: endpoint to be checked
  639.  *
  640.  * Returns one of USB_ENDPOINT_XFER_{CONTROL, ISOC, BULK, INT} according
  641.  * to @epd's transfer type.
  642.  */
  643. static inline int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
  644. {
  645.     return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
  646. }
  647.  
  648. /**
  649.  * usb_endpoint_dir_in - check if the endpoint has IN direction
  650.  * @epd: endpoint to be checked
  651.  *
  652.  * Returns true if the endpoint is of type IN, otherwise it returns false.
  653.  */
  654. static inline int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
  655. {
  656.     return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
  657. }
  658.  
  659. /**
  660.  * usb_endpoint_dir_out - check if the endpoint has OUT direction
  661.  * @epd: endpoint to be checked
  662.  *
  663.  * Returns true if the endpoint is of type OUT, otherwise it returns false.
  664.  */
  665. static inline int usb_endpoint_dir_out(
  666.                 const struct usb_endpoint_descriptor *epd)
  667. {
  668.     return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
  669. }
  670.  
  671. /**
  672.  * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
  673.  * @epd: endpoint to be checked
  674.  *
  675.  * Returns true if the endpoint is of type bulk, otherwise it returns false.
  676.  */
  677. static inline int usb_endpoint_xfer_bulk(
  678.                 const struct usb_endpoint_descriptor *epd)
  679. {
  680.     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
  681.         USB_ENDPOINT_XFER_BULK);
  682. }
  683.  
  684. /**
  685.  * usb_endpoint_xfer_control - check if the endpoint has control transfer type
  686.  * @epd: endpoint to be checked
  687.  *
  688.  * Returns true if the endpoint is of type control, otherwise it returns false.
  689.  */
  690. static inline int usb_endpoint_xfer_control(
  691.                 const struct usb_endpoint_descriptor *epd)
  692. {
  693.     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
  694.         USB_ENDPOINT_XFER_CONTROL);
  695. }
  696.  
  697. /**
  698.  * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
  699.  * @epd: endpoint to be checked
  700.  *
  701.  * Returns true if the endpoint is of type interrupt, otherwise it returns
  702.  * false.
  703.  */
  704. static inline int usb_endpoint_xfer_int(
  705.                 const struct usb_endpoint_descriptor *epd)
  706. {
  707.     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
  708.         USB_ENDPOINT_XFER_INT);
  709. }
  710.  
  711. /**
  712.  * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
  713.  * @epd: endpoint to be checked
  714.  *
  715.  * Returns true if the endpoint is of type isochronous, otherwise it returns
  716.  * false.
  717.  */
  718. static inline int usb_endpoint_xfer_isoc(
  719.                 const struct usb_endpoint_descriptor *epd)
  720. {
  721.     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
  722.         USB_ENDPOINT_XFER_ISOC);
  723. }
  724.  
  725. /**
  726.  * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
  727.  * @epd: endpoint to be checked
  728.  *
  729.  * Returns true if the endpoint has bulk transfer type and IN direction,
  730.  * otherwise it returns false.
  731.  */
  732. static inline int usb_endpoint_is_bulk_in(
  733.                 const struct usb_endpoint_descriptor *epd)
  734. {
  735.     return (usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd));
  736. }
  737.  
  738. /**
  739.  * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
  740.  * @epd: endpoint to be checked
  741.  *
  742.  * Returns true if the endpoint has bulk transfer type and OUT direction,
  743.  * otherwise it returns false.
  744.  */
  745. static inline int usb_endpoint_is_bulk_out(
  746.                 const struct usb_endpoint_descriptor *epd)
  747. {
  748.     return (usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd));
  749. }
  750.  
  751. /**
  752.  * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
  753.  * @epd: endpoint to be checked
  754.  *
  755.  * Returns true if the endpoint has interrupt transfer type and IN direction,
  756.  * otherwise it returns false.
  757.  */
  758. static inline int usb_endpoint_is_int_in(
  759.                 const struct usb_endpoint_descriptor *epd)
  760. {
  761.     return (usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd));
  762. }
  763.  
  764. /**
  765.  * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
  766.  * @epd: endpoint to be checked
  767.  *
  768.  * Returns true if the endpoint has interrupt transfer type and OUT direction,
  769.  * otherwise it returns false.
  770.  */
  771. static inline int usb_endpoint_is_int_out(
  772.                 const struct usb_endpoint_descriptor *epd)
  773. {
  774.     return (usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd));
  775. }
  776.  
  777. /**
  778.  * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
  779.  * @epd: endpoint to be checked
  780.  *
  781.  * Returns true if the endpoint has isochronous transfer type and IN direction,
  782.  * otherwise it returns false.
  783.  */
  784. static inline int usb_endpoint_is_isoc_in(
  785.                 const struct usb_endpoint_descriptor *epd)
  786. {
  787.     return (usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd));
  788. }
  789.  
  790. /**
  791.  * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
  792.  * @epd: endpoint to be checked
  793.  *
  794.  * Returns true if the endpoint has isochronous transfer type and OUT direction,
  795.  * otherwise it returns false.
  796.  */
  797. static inline int usb_endpoint_is_isoc_out(
  798.                 const struct usb_endpoint_descriptor *epd)
  799. {
  800.     return (usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd));
  801. }
  802.  
  803. /*-------------------------------------------------------------------------*/
  804.  
  805. #define USB_DEVICE_ID_MATCH_DEVICE \
  806.         (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
  807. #define USB_DEVICE_ID_MATCH_DEV_RANGE \
  808.         (USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
  809. #define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
  810.         (USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
  811. #define USB_DEVICE_ID_MATCH_DEV_INFO \
  812.         (USB_DEVICE_ID_MATCH_DEV_CLASS | \
  813.         USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
  814.         USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
  815. #define USB_DEVICE_ID_MATCH_INT_INFO \
  816.         (USB_DEVICE_ID_MATCH_INT_CLASS | \
  817.         USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
  818.         USB_DEVICE_ID_MATCH_INT_PROTOCOL)
  819.  
  820. /**
  821.  * USB_DEVICE - macro used to describe a specific usb device
  822.  * @vend: the 16 bit USB Vendor ID
  823.  * @prod: the 16 bit USB Product ID
  824.  *
  825.  * This macro is used to create a struct usb_device_id that matches a
  826.  * specific device.
  827.  */
  828. #define USB_DEVICE(vend,prod) \
  829.     .match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
  830.     .idVendor = (vend), \
  831.     .idProduct = (prod)
  832. /**
  833.  * USB_DEVICE_VER - describe a specific usb device with a version range
  834.  * @vend: the 16 bit USB Vendor ID
  835.  * @prod: the 16 bit USB Product ID
  836.  * @lo: the bcdDevice_lo value
  837.  * @hi: the bcdDevice_hi value
  838.  *
  839.  * This macro is used to create a struct usb_device_id that matches a
  840.  * specific device, with a version range.
  841.  */
  842. #define USB_DEVICE_VER(vend, prod, lo, hi) \
  843.     .match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
  844.     .idVendor = (vend), \
  845.     .idProduct = (prod), \
  846.     .bcdDevice_lo = (lo), \
  847.     .bcdDevice_hi = (hi)
  848.  
  849. /**
  850.  * USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
  851.  * @vend: the 16 bit USB Vendor ID
  852.  * @prod: the 16 bit USB Product ID
  853.  * @pr: bInterfaceProtocol value
  854.  *
  855.  * This macro is used to create a struct usb_device_id that matches a
  856.  * specific interface protocol of devices.
  857.  */
  858. #define USB_DEVICE_INTERFACE_PROTOCOL(vend, prod, pr) \
  859.     .match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
  860.                USB_DEVICE_ID_MATCH_INT_PROTOCOL, \
  861.     .idVendor = (vend), \
  862.     .idProduct = (prod), \
  863.     .bInterfaceProtocol = (pr)
  864.  
  865. /**
  866.  * USB_DEVICE_INFO - macro used to describe a class of usb devices
  867.  * @cl: bDeviceClass value
  868.  * @sc: bDeviceSubClass value
  869.  * @pr: bDeviceProtocol value
  870.  *
  871.  * This macro is used to create a struct usb_device_id that matches a
  872.  * specific class of devices.
  873.  */
  874. #define USB_DEVICE_INFO(cl, sc, pr) \
  875.     .match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, \
  876.     .bDeviceClass = (cl), \
  877.     .bDeviceSubClass = (sc), \
  878.     .bDeviceProtocol = (pr)
  879.  
  880. /**
  881.  * USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
  882.  * @cl: bInterfaceClass value
  883.  * @sc: bInterfaceSubClass value
  884.  * @pr: bInterfaceProtocol value
  885.  *
  886.  * This macro is used to create a struct usb_device_id that matches a
  887.  * specific class of interfaces.
  888.  */
  889. #define USB_INTERFACE_INFO(cl, sc, pr) \
  890.     .match_flags = USB_DEVICE_ID_MATCH_INT_INFO, \
  891.     .bInterfaceClass = (cl), \
  892.     .bInterfaceSubClass = (sc), \
  893.     .bInterfaceProtocol = (pr)
  894.  
  895. /**
  896.  * USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
  897.  * @vend: the 16 bit USB Vendor ID
  898.  * @prod: the 16 bit USB Product ID
  899.  * @cl: bInterfaceClass value
  900.  * @sc: bInterfaceSubClass value
  901.  * @pr: bInterfaceProtocol value
  902.  *
  903.  * This macro is used to create a struct usb_device_id that matches a
  904.  * specific device with a specific class of interfaces.
  905.  *
  906.  * This is especially useful when explicitly matching devices that have
  907.  * vendor specific bDeviceClass values, but standards-compliant interfaces.
  908.  */
  909. #define USB_DEVICE_AND_INTERFACE_INFO(vend, prod, cl, sc, pr) \
  910.     .match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
  911.         | USB_DEVICE_ID_MATCH_DEVICE, \
  912.     .idVendor = (vend), \
  913.     .idProduct = (prod), \
  914.     .bInterfaceClass = (cl), \
  915.     .bInterfaceSubClass = (sc), \
  916.     .bInterfaceProtocol = (pr)
  917.  
  918. /* ----------------------------------------------------------------------- */
  919.  
  920. /* Stuff for dynamic usb ids */
  921. struct usb_dynids {
  922.     spinlock_t lock;
  923.     struct list_head list;
  924. };
  925.  
  926. struct usb_dynid {
  927.     struct list_head node;
  928.     struct usb_device_id id;
  929. };
  930.  
  931. extern ssize_t usb_store_new_id(struct usb_dynids *dynids,
  932.                 struct device_driver *driver,
  933.                 const char *buf, size_t count);
  934.  
  935. /**
  936.  * struct usbdrv_wrap - wrapper for driver-model structure
  937.  * @driver: The driver-model core driver structure.
  938.  * @for_devices: Non-zero for device drivers, 0 for interface drivers.
  939.  */
  940. struct usbdrv_wrap {
  941.     struct device_driver driver;
  942.     int for_devices;
  943. };
  944.  
  945. /**
  946.  * struct usb_driver - identifies USB interface driver to usbcore
  947.  * @name: The driver name should be unique among USB drivers,
  948.  *    and should normally be the same as the module name.
  949.  * @probe: Called to see if the driver is willing to manage a particular
  950.  *    interface on a device.  If it is, probe returns zero and uses
  951.  *    usb_set_intfdata() to associate driver-specific data with the
  952.  *    interface.  It may also use usb_set_interface() to specify the
  953.  *    appropriate altsetting.  If unwilling to manage the interface,
  954.  *    return -ENODEV, if genuine IO errors occured, an appropriate
  955.  *    negative errno value.
  956.  * @disconnect: Called when the interface is no longer accessible, usually
  957.  *    because its device has been (or is being) disconnected or the
  958.  *    driver module is being unloaded.
  959.  * @ioctl: Used for drivers that want to talk to userspace through
  960.  *    the "usbfs" filesystem.  This lets devices provide ways to
  961.  *    expose information to user space regardless of where they
  962.  *    do (or don't) show up otherwise in the filesystem.
  963.  * @suspend: Called when the device is going to be suspended by the system.
  964.  * @resume: Called when the device is being resumed by the system.
  965.  * @reset_resume: Called when the suspended device has been reset instead
  966.  *    of being resumed.
  967.  * @pre_reset: Called by usb_reset_device() when the device
  968.  *    is about to be reset.
  969.  * @post_reset: Called by usb_reset_device() after the device
  970.  *    has been reset
  971.  * @id_table: USB drivers use ID table to support hotplugging.
  972.  *    Export this with MODULE_DEVICE_TABLE(usb,...).  This must be set
  973.  *    or your driver's probe function will never get called.
  974.  * @dynids: used internally to hold the list of dynamically added device
  975.  *    ids for this driver.
  976.  * @drvwrap: Driver-model core structure wrapper.
  977.  * @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
  978.  *    added to this driver by preventing the sysfs file from being created.
  979.  * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
  980.  *    for interfaces bound to this driver.
  981.  * @soft_unbind: if set to 1, the USB core will not kill URBs and disable
  982.  *    endpoints before calling the driver's disconnect method.
  983.  *
  984.  * USB interface drivers must provide a name, probe() and disconnect()
  985.  * methods, and an id_table.  Other driver fields are optional.
  986.  *
  987.  * The id_table is used in hotplugging.  It holds a set of descriptors,
  988.  * and specialized data may be associated with each entry.  That table
  989.  * is used by both user and kernel mode hotplugging support.
  990.  *
  991.  * The probe() and disconnect() methods are called in a context where
  992.  * they can sleep, but they should avoid abusing the privilege.  Most
  993.  * work to connect to a device should be done when the device is opened,
  994.  * and undone at the last close.  The disconnect code needs to address
  995.  * concurrency issues with respect to open() and close() methods, as
  996.  * well as forcing all pending I/O requests to complete (by unlinking
  997.  * them as necessary, and blocking until the unlinks complete).
  998.  */
  999. struct usb_driver {
  1000.     const char *name;
  1001.  
  1002.     int (*probe) (struct usb_interface *intf,
  1003.               const struct usb_device_id *id);
  1004.  
  1005.     void (*disconnect) (struct usb_interface *intf);
  1006.  
  1007.     int (*ioctl) (struct usb_interface *intf, unsigned int code,
  1008.             void *buf);
  1009.  
  1010.     int (*suspend) (struct usb_interface *intf, pm_message_t message);
  1011.     int (*resume) (struct usb_interface *intf);
  1012.     int (*reset_resume)(struct usb_interface *intf);
  1013.  
  1014.     int (*pre_reset)(struct usb_interface *intf);
  1015.     int (*post_reset)(struct usb_interface *intf);
  1016.  
  1017.     const struct usb_device_id *id_table;
  1018.  
  1019.     struct usb_dynids dynids;
  1020.     struct usbdrv_wrap drvwrap;
  1021.     unsigned int no_dynamic_id:1;
  1022.     unsigned int supports_autosuspend:1;
  1023.     unsigned int soft_unbind:1;
  1024. };
  1025. #define    to_usb_driver(d) container_of(d, struct usb_driver, drvwrap.driver)
  1026.  
  1027. /**
  1028.  * struct usb_device_driver - identifies USB device driver to usbcore
  1029.  * @name: The driver name should be unique among USB drivers,
  1030.  *    and should normally be the same as the module name.
  1031.  * @probe: Called to see if the driver is willing to manage a particular
  1032.  *    device.  If it is, probe returns zero and uses dev_set_drvdata()
  1033.  *    to associate driver-specific data with the device.  If unwilling
  1034.  *    to manage the device, return a negative errno value.
  1035.  * @disconnect: Called when the device is no longer accessible, usually
  1036.  *    because it has been (or is being) disconnected or the driver's
  1037.  *    module is being unloaded.
  1038.  * @suspend: Called when the device is going to be suspended by the system.
  1039.  * @resume: Called when the device is being resumed by the system.
  1040.  * @drvwrap: Driver-model core structure wrapper.
  1041.  * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
  1042.  *    for devices bound to this driver.
  1043.  *
  1044.  * USB drivers must provide all the fields listed above except drvwrap.
  1045.  */
  1046. struct usb_device_driver {
  1047.     const char *name;
  1048.  
  1049.     int (*probe) (struct usb_device *udev);
  1050.     void (*disconnect) (struct usb_device *udev);
  1051.  
  1052.     int (*suspend) (struct usb_device *udev, pm_message_t message);
  1053.     int (*resume) (struct usb_device *udev);
  1054.     struct usbdrv_wrap drvwrap;
  1055.     unsigned int supports_autosuspend:1;
  1056. };
  1057. #define    to_usb_device_driver(d) container_of(d, struct usb_device_driver, \
  1058.         drvwrap.driver)
  1059.  
  1060. extern struct bus_type usb_bus_type;
  1061.  
  1062. /**
  1063.  * struct usb_class_driver - identifies a USB driver that wants to use the USB major number
  1064.  * @name: the usb class device name for this driver.  Will show up in sysfs.
  1065.  * @fops: pointer to the struct file_operations of this driver.
  1066.  * @minor_base: the start of the minor range for this driver.
  1067.  *
  1068.  * This structure is used for the usb_register_dev() and
  1069.  * usb_unregister_dev() functions, to consolidate a number of the
  1070.  * parameters used for them.
  1071.  */
  1072. struct usb_class_driver {
  1073.     char *name;
  1074.     const struct file_operations *fops;
  1075.     int minor_base;
  1076. };
  1077.  
  1078. /*
  1079.  * use these in module_init()/module_exit()
  1080.  * and don't forget MODULE_DEVICE_TABLE(usb, ...)
  1081.  */
  1082. extern int usb_register_driver(struct usb_driver *, struct module *,
  1083.                    const char *);
  1084. static inline int usb_register(struct usb_driver *driver)
  1085. {
  1086.     return usb_register_driver(driver, THIS_MODULE, KBUILD_MODNAME);
  1087. }
  1088. extern void usb_deregister(struct usb_driver *);
  1089.  
  1090. extern int usb_register_device_driver(struct usb_device_driver *,
  1091.             struct module *);
  1092. extern void usb_deregister_device_driver(struct usb_device_driver *);
  1093.  
  1094. extern int usb_register_dev(struct usb_interface *intf,
  1095.                 struct usb_class_driver *class_driver);
  1096. extern void usb_deregister_dev(struct usb_interface *intf,
  1097.                    struct usb_class_driver *class_driver);
  1098.  
  1099. extern int usb_disabled(void);
  1100.  
  1101. /* ----------------------------------------------------------------------- */
  1102.  
  1103. /*
  1104.  * URB support, for asynchronous request completions
  1105.  */
  1106.  
  1107. /*
  1108.  * urb->transfer_flags:
  1109.  *
  1110.  * Note: URB_DIR_IN/OUT is automatically set in usb_submit_urb().
  1111.  */
  1112. #define URB_SHORT_NOT_OK    0x0001    /* report short reads as errors */
  1113. #define URB_ISO_ASAP        0x0002    /* iso-only, urb->start_frame
  1114.                      * ignored */
  1115. #define URB_NO_TRANSFER_DMA_MAP    0x0004    /* urb->transfer_dma valid on submit */
  1116. #define URB_NO_SETUP_DMA_MAP    0x0008    /* urb->setup_dma valid on submit */
  1117. #define URB_NO_FSBR        0x0020    /* UHCI-specific */
  1118. #define URB_ZERO_PACKET        0x0040    /* Finish bulk OUT with short packet */
  1119. #define URB_NO_INTERRUPT    0x0080    /* HINT: no non-error interrupt
  1120.                      * needed */
  1121. #define URB_FREE_BUFFER        0x0100    /* Free transfer buffer with the URB */
  1122.  
  1123. #define URB_DIR_IN        0x0200    /* Transfer from device to host */
  1124. #define URB_DIR_OUT        0
  1125. #define URB_DIR_MASK        URB_DIR_IN
  1126.  
  1127. struct usb_iso_packet_descriptor {
  1128.     unsigned int offset;
  1129.     unsigned int length;        /* expected length */
  1130.     unsigned int actual_length;
  1131.     int status;
  1132. };
  1133.  
  1134. struct urb;
  1135.  
  1136. struct usb_anchor {
  1137.     struct list_head urb_list;
  1138.     wait_queue_head_t wait;
  1139.     spinlock_t lock;
  1140.     unsigned int poisoned:1;
  1141. };
  1142.  
  1143. static inline void init_usb_anchor(struct usb_anchor *anchor)
  1144. {
  1145.     INIT_LIST_HEAD(&anchor->urb_list);
  1146.     init_waitqueue_head(&anchor->wait);
  1147.     spin_lock_init(&anchor->lock);
  1148. }
  1149.  
  1150. typedef void (*usb_complete_t)(struct urb *);
  1151.  
  1152. /**
  1153.  * struct urb - USB Request Block
  1154.  * @urb_list: For use by current owner of the URB.
  1155.  * @anchor_list: membership in the list of an anchor
  1156.  * @anchor: to anchor URBs to a common mooring
  1157.  * @ep: Points to the endpoint's data structure.  Will eventually
  1158.  *    replace @pipe.
  1159.  * @pipe: Holds endpoint number, direction, type, and more.
  1160.  *    Create these values with the eight macros available;
  1161.  *    usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is "ctrl"
  1162.  *    (control), "bulk", "int" (interrupt), or "iso" (isochronous).
  1163.  *    For example usb_sndbulkpipe() or usb_rcvintpipe().  Endpoint
  1164.  *    numbers range from zero to fifteen.  Note that "in" endpoint two
  1165.  *    is a different endpoint (and pipe) from "out" endpoint two.
  1166.  *    The current configuration controls the existence, type, and
  1167.  *    maximum packet size of any given endpoint.
  1168.  * @dev: Identifies the USB device to perform the request.
  1169.  * @status: This is read in non-iso completion functions to get the
  1170.  *    status of the particular request.  ISO requests only use it
  1171.  *    to tell whether the URB was unlinked; detailed status for
  1172.  *    each frame is in the fields of the iso_frame-desc.
  1173.  * @transfer_flags: A variety of flags may be used to affect how URB
  1174.  *    submission, unlinking, or operation are handled.  Different
  1175.  *    kinds of URB can use different flags.
  1176.  * @transfer_buffer:  This identifies the buffer to (or from) which
  1177.  *     the I/O request will be performed (unless URB_NO_TRANSFER_DMA_MAP
  1178.  *    is set).  This buffer must be suitable for DMA; allocate it with
  1179.  *    kmalloc() or equivalent.  For transfers to "in" endpoints, contents
  1180.  *    of this buffer will be modified.  This buffer is used for the data
  1181.  *    stage of control transfers.
  1182.  * @transfer_dma: When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
  1183.  *    the device driver is saying that it provided this DMA address,
  1184.  *    which the host controller driver should use in preference to the
  1185.  *    transfer_buffer.
  1186.  * @transfer_buffer_length: How big is transfer_buffer.  The transfer may
  1187.  *    be broken up into chunks according to the current maximum packet
  1188.  *    size for the endpoint, which is a function of the configuration
  1189.  *    and is encoded in the pipe.  When the length is zero, neither
  1190.  *    transfer_buffer nor transfer_dma is used.
  1191.  * @actual_length: This is read in non-iso completion functions, and
  1192.  *    it tells how many bytes (out of transfer_buffer_length) were
  1193.  *    transferred.  It will normally be the same as requested, unless
  1194.  *    either an error was reported or a short read was performed.
  1195.  *    The URB_SHORT_NOT_OK transfer flag may be used to make such
  1196.  *    short reads be reported as errors.
  1197.  * @setup_packet: Only used for control transfers, this points to eight bytes
  1198.  *    of setup data.  Control transfers always start by sending this data
  1199.  *    to the device.  Then transfer_buffer is read or written, if needed.
  1200.  * @setup_dma: For control transfers with URB_NO_SETUP_DMA_MAP set, the
  1201.  *    device driver has provided this DMA address for the setup packet.
  1202.  *    The host controller driver should use this in preference to
  1203.  *    setup_packet.
  1204.  * @start_frame: Returns the initial frame for isochronous transfers.
  1205.  * @number_of_packets: Lists the number of ISO transfer buffers.
  1206.  * @interval: Specifies the polling interval for interrupt or isochronous
  1207.  *    transfers.  The units are frames (milliseconds) for for full and low
  1208.  *    speed devices, and microframes (1/8 millisecond) for highspeed ones.
  1209.  * @error_count: Returns the number of ISO transfers that reported errors.
  1210.  * @context: For use in completion functions.  This normally points to
  1211.  *    request-specific driver context.
  1212.  * @complete: Completion handler. This URB is passed as the parameter to the
  1213.  *    completion function.  The completion function may then do what
  1214.  *    it likes with the URB, including resubmitting or freeing it.
  1215.  * @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to
  1216.  *    collect the transfer status for each buffer.
  1217.  *
  1218.  * This structure identifies USB transfer requests.  URBs must be allocated by
  1219.  * calling usb_alloc_urb() and freed with a call to usb_free_urb().
  1220.  * Initialization may be done using various usb_fill_*_urb() functions.  URBs
  1221.  * are submitted using usb_submit_urb(), and pending requests may be canceled
  1222.  * using usb_unlink_urb() or usb_kill_urb().
  1223.  *
  1224.  * Data Transfer Buffers:
  1225.  *
  1226.  * Normally drivers provide I/O buffers allocated with kmalloc() or otherwise
  1227.  * taken from the general page pool.  That is provided by transfer_buffer
  1228.  * (control requests also use setup_packet), and host controller drivers
  1229.  * perform a dma mapping (and unmapping) for each buffer transferred.  Those
  1230.  * mapping operations can be expensive on some platforms (perhaps using a dma
  1231.  * bounce buffer or talking to an IOMMU),
  1232.  * although they're cheap on commodity x86 and ppc hardware.
  1233.  *
  1234.  * Alternatively, drivers may pass the URB_NO_xxx_DMA_MAP transfer flags,
  1235.  * which tell the host controller driver that no such mapping is needed since
  1236.  * the device driver is DMA-aware.  For example, a device driver might
  1237.  * allocate a DMA buffer with usb_buffer_alloc() or call usb_buffer_map().
  1238.  * When these transfer flags are provided, host controller drivers will
  1239.  * attempt to use the dma addresses found in the transfer_dma and/or
  1240.  * setup_dma fields rather than determining a dma address themselves.  (Note
  1241.  * that transfer_buffer and setup_packet must still be set because not all
  1242.  * host controllers use DMA, nor do virtual root hubs).
  1243.  *
  1244.  * Initialization:
  1245.  *
  1246.  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
  1247.  * zero), and complete fields.  All URBs must also initialize
  1248.  * transfer_buffer and transfer_buffer_length.  They may provide the
  1249.  * URB_SHORT_NOT_OK transfer flag, indicating that short reads are
  1250.  * to be treated as errors; that flag is invalid for write requests.
  1251.  *
  1252.  * Bulk URBs may
  1253.  * use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
  1254.  * should always terminate with a short packet, even if it means adding an
  1255.  * extra zero length packet.
  1256.  *
  1257.  * Control URBs must provide a setup_packet.  The setup_packet and
  1258.  * transfer_buffer may each be mapped for DMA or not, independently of
  1259.  * the other.  The transfer_flags bits URB_NO_TRANSFER_DMA_MAP and
  1260.  * URB_NO_SETUP_DMA_MAP indicate which buffers have already been mapped.
  1261.  * URB_NO_SETUP_DMA_MAP is ignored for non-control URBs.
  1262.  *
  1263.  * Interrupt URBs must provide an interval, saying how often (in milliseconds
  1264.  * or, for highspeed devices, 125 microsecond units)
  1265.  * to poll for transfers.  After the URB has been submitted, the interval
  1266.  * field reflects how the transfer was actually scheduled.
  1267.  * The polling interval may be more frequent than requested.
  1268.  * For example, some controllers have a maximum interval of 32 milliseconds,
  1269.  * while others support intervals of up to 1024 milliseconds.
  1270.  * Isochronous URBs also have transfer intervals.  (Note that for isochronous
  1271.  * endpoints, as well as high speed interrupt endpoints, the encoding of
  1272.  * the transfer interval in the endpoint descriptor is logarithmic.
  1273.  * Device drivers must convert that value to linear units themselves.)
  1274.  *
  1275.  * Isochronous URBs normally use the URB_ISO_ASAP transfer flag, telling
  1276.  * the host controller to schedule the transfer as soon as bandwidth
  1277.  * utilization allows, and then set start_frame to reflect the actual frame
  1278.  * selected during submission.  Otherwise drivers must specify the start_frame
  1279.  * and handle the case where the transfer can't begin then.  However, drivers
  1280.  * won't know how bandwidth is currently allocated, and while they can
  1281.  * find the current frame using usb_get_current_frame_number () they can't
  1282.  * know the range for that frame number.  (Ranges for frame counter values
  1283.  * are HC-specific, and can go from 256 to 65536 frames from "now".)
  1284.  *
  1285.  * Isochronous URBs have a different data transfer model, in part because
  1286.  * the quality of service is only "best effort".  Callers provide specially
  1287.  * allocated URBs, with number_of_packets worth of iso_frame_desc structures
  1288.  * at the end.  Each such packet is an individual ISO transfer.  Isochronous
  1289.  * URBs are normally queued, submitted by drivers to arrange that
  1290.  * transfers are at least double buffered, and then explicitly resubmitted
  1291.  * in completion handlers, so
  1292.  * that data (such as audio or video) streams at as constant a rate as the
  1293.  * host controller scheduler can support.
  1294.  *
  1295.  * Completion Callbacks:
  1296.  *
  1297.  * The completion callback is made in_interrupt(), and one of the first
  1298.  * things that a completion handler should do is check the status field.
  1299.  * The status field is provided for all URBs.  It is used to report
  1300.  * unlinked URBs, and status for all non-ISO transfers.  It should not
  1301.  * be examined before the URB is returned to the completion handler.
  1302.  *
  1303.  * The context field is normally used to link URBs back to the relevant
  1304.  * driver or request state.
  1305.  *
  1306.  * When the completion callback is invoked for non-isochronous URBs, the
  1307.  * actual_length field tells how many bytes were transferred.  This field
  1308.  * is updated even when the URB terminated with an error or was unlinked.
  1309.  *
  1310.  * ISO transfer status is reported in the status and actual_length fields
  1311.  * of the iso_frame_desc array, and the number of errors is reported in
  1312.  * error_count.  Completion callbacks for ISO transfers will normally
  1313.  * (re)submit URBs to ensure a constant transfer rate.
  1314.  *
  1315.  * Note that even fields marked "public" should not be touched by the driver
  1316.  * when the urb is owned by the hcd, that is, since the call to
  1317.  * usb_submit_urb() till the entry into the completion routine.
  1318.  */
  1319. struct urb {
  1320.     /* private: usb core and host controller only fields in the urb */
  1321.     struct kref kref;        /* reference count of the URB */
  1322.     void *hcpriv;            /* private data for host controller */
  1323.     atomic_t use_count;        /* concurrent submissions counter */
  1324.     u8 reject;            /* submissions will fail */
  1325.     int unlinked;            /* unlink error code */
  1326.  
  1327.     /* public: documented fields in the urb that can be used by drivers */
  1328.     struct list_head urb_list;    /* list head for use by the urb's
  1329.                      * current owner */
  1330.     struct list_head anchor_list;    /* the URB may be anchored */
  1331.     struct usb_anchor *anchor;
  1332.     struct usb_device *dev;     /* (in) pointer to associated device */
  1333.     struct usb_host_endpoint *ep;    /* (internal) pointer to endpoint */
  1334.     unsigned int pipe;        /* (in) pipe information */
  1335.     int status;            /* (return) non-ISO status */
  1336.     unsigned int transfer_flags;    /* (in) URB_SHORT_NOT_OK | ...*/
  1337.     void *transfer_buffer;        /* (in) associated data buffer */
  1338.     dma_addr_t transfer_dma;    /* (in) dma addr for transfer_buffer */
  1339.     int transfer_buffer_length;    /* (in) data buffer length */
  1340.     int actual_length;        /* (return) actual transfer length */
  1341.     unsigned char *setup_packet;    /* (in) setup packet (control only) */
  1342.     dma_addr_t setup_dma;        /* (in) dma addr for setup_packet */
  1343.     int start_frame;        /* (modify) start frame (ISO) */
  1344.     int number_of_packets;        /* (in) number of ISO packets */
  1345.     int interval;            /* (modify) transfer interval
  1346.                      * (INT/ISO) */
  1347.     int error_count;        /* (return) number of ISO errors */
  1348.     void *context;            /* (in) context for completion */
  1349.     usb_complete_t complete;    /* (in) completion routine */
  1350.     struct usb_iso_packet_descriptor iso_frame_desc[0];
  1351.                     /* (in) ISO ONLY */
  1352. };
  1353.  
  1354. /* ----------------------------------------------------------------------- */
  1355.  
  1356. /**
  1357.  * usb_fill_control_urb - initializes a control urb
  1358.  * @urb: pointer to the urb to initialize.
  1359.  * @dev: pointer to the struct usb_device for this urb.
  1360.  * @pipe: the endpoint pipe
  1361.  * @setup_packet: pointer to the setup_packet buffer
  1362.  * @transfer_buffer: pointer to the transfer buffer
  1363.  * @buffer_length: length of the transfer buffer
  1364.  * @complete_fn: pointer to the usb_complete_t function
  1365.  * @context: what to set the urb context to.
  1366.  *
  1367.  * Initializes a control urb with the proper information needed to submit
  1368.  * it to a device.
  1369.  */
  1370. static inline void usb_fill_control_urb(struct urb *urb,
  1371.                     struct usb_device *dev,
  1372.                     unsigned int pipe,
  1373.                     unsigned char *setup_packet,
  1374.                     void *transfer_buffer,
  1375.                     int buffer_length,
  1376.                     usb_complete_t complete_fn,
  1377.                     void *context)
  1378. {
  1379.     urb->dev = dev;
  1380.     urb->pipe = pipe;
  1381.     urb->setup_packet = setup_packet;
  1382.     urb->transfer_buffer = transfer_buffer;
  1383.     urb->transfer_buffer_length = buffer_length;
  1384.     urb->complete = complete_fn;
  1385.     urb->context = context;
  1386. }
  1387.  
  1388. /**
  1389.  * usb_fill_bulk_urb - macro to help initialize a bulk urb
  1390.  * @urb: pointer to the urb to initialize.
  1391.  * @dev: pointer to the struct usb_device for this urb.
  1392.  * @pipe: the endpoint pipe
  1393.  * @transfer_buffer: pointer to the transfer buffer
  1394.  * @buffer_length: length of the transfer buffer
  1395.  * @complete_fn: pointer to the usb_complete_t function
  1396.  * @context: what to set the urb context to.
  1397.  *
  1398.  * Initializes a bulk urb with the proper information needed to submit it
  1399.  * to a device.
  1400.  */
  1401. static inline void usb_fill_bulk_urb(struct urb *urb,
  1402.                      struct usb_device *dev,
  1403.                      unsigned int pipe,
  1404.                      void *transfer_buffer,
  1405.                      int buffer_length,
  1406.                      usb_complete_t complete_fn,
  1407.                      void *context)
  1408. {
  1409.     urb->dev = dev;
  1410.     urb->pipe = pipe;
  1411.     urb->transfer_buffer = transfer_buffer;
  1412.     urb->transfer_buffer_length = buffer_length;
  1413.     urb->complete = complete_fn;
  1414.     urb->context = context;
  1415. }
  1416.  
  1417. /**
  1418.  * usb_fill_int_urb - macro to help initialize a interrupt urb
  1419.  * @urb: pointer to the urb to initialize.
  1420.  * @dev: pointer to the struct usb_device for this urb.
  1421.  * @pipe: the endpoint pipe
  1422.  * @transfer_buffer: pointer to the transfer buffer
  1423.  * @buffer_length: length of the transfer buffer
  1424.  * @complete_fn: pointer to the usb_complete_t function
  1425.  * @context: what to set the urb context to.
  1426.  * @interval: what to set the urb interval to, encoded like
  1427.  *    the endpoint descriptor's bInterval value.
  1428.  *
  1429.  * Initializes a interrupt urb with the proper information needed to submit
  1430.  * it to a device.
  1431.  * Note that high speed interrupt endpoints use a logarithmic encoding of
  1432.  * the endpoint interval, and express polling intervals in microframes
  1433.  * (eight per millisecond) rather than in frames (one per millisecond).
  1434.  */
  1435. static inline void usb_fill_int_urb(struct urb *urb,
  1436.                     struct usb_device *dev,
  1437.                     unsigned int pipe,
  1438.                     void *transfer_buffer,
  1439.                     int buffer_length,
  1440.                     usb_complete_t complete_fn,
  1441.                     void *context,
  1442.                     int interval)
  1443. {
  1444.     urb->dev = dev;
  1445.     urb->pipe = pipe;
  1446.     urb->transfer_buffer = transfer_buffer;
  1447.     urb->transfer_buffer_length = buffer_length;
  1448.     urb->complete = complete_fn;
  1449.     urb->context = context;
  1450.     if (dev->speed == USB_SPEED_HIGH)
  1451.         urb->interval = 1 << (interval - 1);
  1452.     else
  1453.         urb->interval = interval;
  1454.     urb->start_frame = -1;
  1455. }
  1456.  
  1457. extern void usb_init_urb(struct urb *urb);
  1458. extern struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags);
  1459. extern void usb_free_urb(struct urb *urb);
  1460. #define usb_put_urb usb_free_urb
  1461. extern struct urb *usb_get_urb(struct urb *urb);
  1462. extern int usb_submit_urb(struct urb *urb, gfp_t mem_flags);
  1463. extern int usb_unlink_urb(struct urb *urb);
  1464. extern void usb_kill_urb(struct urb *urb);
  1465. extern void usb_poison_urb(struct urb *urb);
  1466. extern void usb_unpoison_urb(struct urb *urb);
  1467. extern void usb_kill_anchored_urbs(struct usb_anchor *anchor);
  1468. extern void usb_poison_anchored_urbs(struct usb_anchor *anchor);
  1469. extern void usb_unlink_anchored_urbs(struct usb_anchor *anchor);
  1470. extern void usb_anchor_urb(struct urb *urb, struct usb_anchor *anchor);
  1471. extern void usb_unanchor_urb(struct urb *urb);
  1472. extern int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
  1473.                      unsigned int timeout);
  1474. extern struct urb *usb_get_from_anchor(struct usb_anchor *anchor);
  1475. extern void usb_scuttle_anchored_urbs(struct usb_anchor *anchor);
  1476. extern int usb_anchor_empty(struct usb_anchor *anchor);
  1477.  
  1478. /**
  1479.  * usb_urb_dir_in - check if an URB describes an IN transfer
  1480.  * @urb: URB to be checked
  1481.  *
  1482.  * Returns 1 if @urb describes an IN transfer (device-to-host),
  1483.  * otherwise 0.
  1484.  */
  1485. static inline int usb_urb_dir_in(struct urb *urb)
  1486. {
  1487.     return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_IN;
  1488. }
  1489.  
  1490. /**
  1491.  * usb_urb_dir_out - check if an URB describes an OUT transfer
  1492.  * @urb: URB to be checked
  1493.  *
  1494.  * Returns 1 if @urb describes an OUT transfer (host-to-device),
  1495.  * otherwise 0.
  1496.  */
  1497. static inline int usb_urb_dir_out(struct urb *urb)
  1498. {
  1499.     return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_OUT;
  1500. }
  1501.  
  1502. void *usb_buffer_alloc(struct usb_device *dev, size_t size,
  1503.     gfp_t mem_flags, dma_addr_t *dma);
  1504. void usb_buffer_free(struct usb_device *dev, size_t size,
  1505.     void *addr, dma_addr_t dma);
  1506.  
  1507. #if 0
  1508. struct urb *usb_buffer_map(struct urb *urb);
  1509. void usb_buffer_dmasync(struct urb *urb);
  1510. void usb_buffer_unmap(struct urb *urb);
  1511. #endif
  1512.  
  1513. struct scatterlist;
  1514. int usb_buffer_map_sg(const struct usb_device *dev, int is_in,
  1515.               struct scatterlist *sg, int nents);
  1516. #if 0
  1517. void usb_buffer_dmasync_sg(const struct usb_device *dev, int is_in,
  1518.                struct scatterlist *sg, int n_hw_ents);
  1519. #endif
  1520. void usb_buffer_unmap_sg(const struct usb_device *dev, int is_in,
  1521.              struct scatterlist *sg, int n_hw_ents);
  1522.  
  1523. /*-------------------------------------------------------------------*
  1524.  *                         SYNCHRONOUS CALL SUPPORT                  *
  1525.  *-------------------------------------------------------------------*/
  1526.  
  1527. extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
  1528.     __u8 request, __u8 requesttype, __u16 value, __u16 index,
  1529.     void *data, __u16 size, int timeout);
  1530. extern int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
  1531.     void *data, int len, int *actual_length, int timeout);
  1532. extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
  1533.     void *data, int len, int *actual_length,
  1534.     int timeout);
  1535.  
  1536. /* wrappers around usb_control_msg() for the most common standard requests */
  1537. extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
  1538.     unsigned char descindex, void *buf, int size);
  1539. extern int usb_get_status(struct usb_device *dev,
  1540.     int type, int target, void *data);
  1541. extern int usb_string(struct usb_device *dev, int index,
  1542.     char *buf, size_t size);
  1543.  
  1544. /* wrappers that also update important state inside usbcore */
  1545. extern int usb_clear_halt(struct usb_device *dev, int pipe);
  1546. extern int usb_reset_configuration(struct usb_device *dev);
  1547. extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
  1548.  
  1549. /* this request isn't really synchronous, but it belongs with the others */
  1550. extern int usb_driver_set_configuration(struct usb_device *udev, int config);
  1551.  
  1552. /*
  1553.  * timeouts, in milliseconds, used for sending/receiving control messages
  1554.  * they typically complete within a few frames (msec) after they're issued
  1555.  * USB identifies 5 second timeouts, maybe more in a few cases, and a few
  1556.  * slow devices (like some MGE Ellipse UPSes) actually push that limit.
  1557.  */
  1558. #define USB_CTRL_GET_TIMEOUT    5000
  1559. #define USB_CTRL_SET_TIMEOUT    5000
  1560.  
  1561.  
  1562. /**
  1563.  * struct usb_sg_request - support for scatter/gather I/O
  1564.  * @status: zero indicates success, else negative errno
  1565.  * @bytes: counts bytes transferred.
  1566.  *
  1567.  * These requests are initialized using usb_sg_init(), and then are used
  1568.  * as request handles passed to usb_sg_wait() or usb_sg_cancel().  Most
  1569.  * members of the request object aren't for driver access.
  1570.  *
  1571.  * The status and bytecount values are valid only after usb_sg_wait()
  1572.  * returns.  If the status is zero, then the bytecount matches the total
  1573.  * from the request.
  1574.  *
  1575.  * After an error completion, drivers may need to clear a halt condition
  1576.  * on the endpoint.
  1577.  */
  1578. struct usb_sg_request {
  1579.     int            status;
  1580.     size_t            bytes;
  1581.  
  1582.     /*
  1583.      * members below are private: to usbcore,
  1584.      * and are not provided for driver access!
  1585.      */
  1586.     spinlock_t        lock;
  1587.  
  1588.     struct usb_device    *dev;
  1589.     int            pipe;
  1590.     struct scatterlist    *sg;
  1591.     int            nents;
  1592.  
  1593.     int            entries;
  1594.     struct urb        **urbs;
  1595.  
  1596.     int            count;
  1597.     struct completion    complete;
  1598. };
  1599.  
  1600. int usb_sg_init(
  1601.     struct usb_sg_request    *io,
  1602.     struct usb_device    *dev,
  1603.     unsigned        pipe,
  1604.     unsigned        period,
  1605.     struct scatterlist    *sg,
  1606.     int            nents,
  1607.     size_t            length,
  1608.     gfp_t            mem_flags
  1609. );
  1610. void usb_sg_cancel(struct usb_sg_request *io);
  1611. void usb_sg_wait(struct usb_sg_request *io);
  1612.  
  1613.  
  1614. /* ----------------------------------------------------------------------- */
  1615.  
  1616. /*
  1617.  * For various legacy reasons, Linux has a small cookie that's paired with
  1618.  * a struct usb_device to identify an endpoint queue.  Queue characteristics
  1619.  * are defined by the endpoint's descriptor.  This cookie is called a "pipe",
  1620.  * an unsigned int encoded as:
  1621.  *
  1622.  *  - direction:    bit 7        (0 = Host-to-Device [Out],
  1623.  *                     1 = Device-to-Host [In] ...
  1624.  *                    like endpoint bEndpointAddress)
  1625.  *  - device address:    bits 8-14       ... bit positions known to uhci-hcd
  1626.  *  - endpoint:        bits 15-18      ... bit positions known to uhci-hcd
  1627.  *  - pipe type:    bits 30-31    (00 = isochronous, 01 = interrupt,
  1628.  *                     10 = control, 11 = bulk)
  1629.  *
  1630.  * Given the device address and endpoint descriptor, pipes are redundant.
  1631.  */
  1632.  
  1633. /* NOTE:  these are not the standard USB_ENDPOINT_XFER_* values!! */
  1634. /* (yet ... they're the values used by usbfs) */
  1635. #define PIPE_ISOCHRONOUS        0
  1636. #define PIPE_INTERRUPT            1
  1637. #define PIPE_CONTROL            2
  1638. #define PIPE_BULK            3
  1639.  
  1640. #define usb_pipein(pipe)    ((pipe) & USB_DIR_IN)
  1641. #define usb_pipeout(pipe)    (!usb_pipein(pipe))
  1642.  
  1643. #define usb_pipedevice(pipe)    (((pipe) >> 8) & 0x7f)
  1644. #define usb_pipeendpoint(pipe)    (((pipe) >> 15) & 0xf)
  1645.  
  1646. #define usb_pipetype(pipe)    (((pipe) >> 30) & 3)
  1647. #define usb_pipeisoc(pipe)    (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
  1648. #define usb_pipeint(pipe)    (usb_pipetype((pipe)) == PIPE_INTERRUPT)
  1649. #define usb_pipecontrol(pipe)    (usb_pipetype((pipe)) == PIPE_CONTROL)
  1650. #define usb_pipebulk(pipe)    (usb_pipetype((pipe)) == PIPE_BULK)
  1651.  
  1652. /* The D0/D1 toggle bits ... USE WITH CAUTION (they're almost hcd-internal) */
  1653. #define usb_gettoggle(dev, ep, out) (((dev)->toggle[out] >> (ep)) & 1)
  1654. #define    usb_dotoggle(dev, ep, out)  ((dev)->toggle[out] ^= (1 << (ep)))
  1655. #define usb_settoggle(dev, ep, out, bit) \
  1656.         ((dev)->toggle[out] = ((dev)->toggle[out] & ~(1 << (ep))) | \
  1657.          ((bit) << (ep)))
  1658.  
  1659.  
  1660. static inline unsigned int __create_pipe(struct usb_device *dev,
  1661.         unsigned int endpoint)
  1662. {
  1663.     return (dev->devnum << 8) | (endpoint << 15);
  1664. }
  1665.  
  1666. /* Create various pipes... */
  1667. #define usb_sndctrlpipe(dev,endpoint)    \
  1668.     ((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint))
  1669. #define usb_rcvctrlpipe(dev,endpoint)    \
  1670.     ((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
  1671. #define usb_sndisocpipe(dev,endpoint)    \
  1672.     ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint))
  1673. #define usb_rcvisocpipe(dev,endpoint)    \
  1674.     ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
  1675. #define usb_sndbulkpipe(dev,endpoint)    \
  1676.     ((PIPE_BULK << 30) | __create_pipe(dev, endpoint))
  1677. #define usb_rcvbulkpipe(dev,endpoint)    \
  1678.     ((PIPE_BULK << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
  1679. #define usb_sndintpipe(dev,endpoint)    \
  1680.     ((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint))
  1681. #define usb_rcvintpipe(dev,endpoint)    \
  1682.     ((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
  1683.  
  1684. /*-------------------------------------------------------------------------*/
  1685.  
  1686. static inline __u16
  1687. usb_maxpacket(struct usb_device *udev, int pipe, int is_out)
  1688. {
  1689.     struct usb_host_endpoint    *ep;
  1690.     unsigned            epnum = usb_pipeendpoint(pipe);
  1691.  
  1692.     if (is_out) {
  1693.         WARN_ON(usb_pipein(pipe));
  1694.         ep = udev->ep_out[epnum];
  1695.     } else {
  1696.         WARN_ON(usb_pipeout(pipe));
  1697.         ep = udev->ep_in[epnum];
  1698.     }
  1699.     if (!ep)
  1700.         return 0;
  1701.  
  1702.     /* NOTE:  only 0x07ff bits are for packet size... */
  1703.     return le16_to_cpu(ep->desc.wMaxPacketSize);
  1704. }
  1705.  
  1706. /* ----------------------------------------------------------------------- */
  1707.  
  1708. /* Events from the usb core */
  1709. #define USB_DEVICE_ADD        0x0001
  1710. #define USB_DEVICE_REMOVE    0x0002
  1711. #define USB_BUS_ADD        0x0003
  1712. #define USB_BUS_REMOVE        0x0004
  1713. extern void usb_register_notify(struct notifier_block *nb);
  1714. extern void usb_unregister_notify(struct notifier_block *nb);
  1715.  
  1716. #ifdef DEBUG
  1717. #define dbg(format, arg...) printk(KERN_DEBUG "%s: " format "\n" , \
  1718.     __FILE__ , ## arg)
  1719. #else
  1720. #define dbg(format, arg...) do {} while (0)
  1721. #endif
  1722.  
  1723. #define err(format, arg...) printk(KERN_ERR KBUILD_MODNAME ": " \
  1724.     format "\n" , ## arg)
  1725. #define info(format, arg...) printk(KERN_INFO KBUILD_MODNAME ": " \
  1726.     format "\n" , ## arg)
  1727. #define warn(format, arg...) printk(KERN_WARNING KBUILD_MODNAME ": " \
  1728.     format "\n" , ## arg)
  1729.  
  1730. #endif  /* __KERNEL__ */
  1731.  
  1732. #endif
  1733.